MPCreateTask

MPCreateTask
Header:	Multiprocessing.h		Carbon status:	Supported

Creates a preemptive task.

OSStatus MPCreateTask (
    TaskProc entryPoint, 
    void *parameter, 
    ByteCount stackSize, 
    MPQueueID notifyQueue, 
    void *terminationParameter1, 
    void *terminationParameter2, 
    MPTaskOptions options, 
    MPTaskID *task
);

entryPoint: A pointer to the task function. The task function should take a single 32-bit parameter and return a value of type OSStatus.
parameter: The parameter to pass to the task function.
stackSize: The size of the stack assigned to the task. Note that you should be careful not to exceed the bounds of the stack, since stack overflows may not be detected. Specifying zero for the size will result in a default stack size of 4KB.
notifyQueue: The ID of the message queue to which the system will send a message when the task terminates. You specify the first 64-bits of the message in the parameters terminationParameter1 and terminationParameter2 respectively. The last 32-bits contain the result code of the task function.
terminationParameter1: A 32-bit value that is sent to the message queue specified by the parameter notifyQueue when the task terminates.
terminationParameter2: A 32-bit value that is sent to the message queue specified by the parameter notifyQueue when the task terminates.
options: Optional attributes of the preemptive task. See “Task Creation Options” for a list of possible values.
task: On return, task points to the ID of the newly created task.

function result: A result code. If MPCreateTask could not create the task because some critical resource was not available, the function returns kMPInsufficientResourcesErr. Usually this is due to lack of memory to allocate the internal data structures associated with the task or the stack. The function also returns kMPInsufficientResourcesErr if any reserved option bits are set.

DISCUSSION

Tasks are created in the unblocked state, ready for execution. A task can terminate in the following ways:

By returning from its entry point
By calling MPExit
When specified as the target of an MPTerminateTask call
If a hardware-detected exception or programming exception occurs and no exception handler is installed
If the application calls ExitToShell

Task resources (its stack, active timers, internal structures related to the task, and so on) are reclaimed by the system when the task terminates. The task's address space is inherited from the process address space. All existing tasks are terminated when the owning process terminates.

To set the relative processor weight to be assigned to a task, use the function MPSetTaskWeight.

See also the function MPTerminateTask.

VERSION NOTES

Introduced with Multiprocessing Services 1.0.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when MPLibrary 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by MPLibrary 1.0 and later.